/* This file is part of libschrift.
 *
 * © 2019-2022 Thomas Oltmann and contributors
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */

#ifndef SCHRIFT_H
#define SCHRIFT_H 1  // 头文件包含保护，防止重复包含

#include <stddef.h>  // 包含标准库头文件，提供 size_t 类型定义
#include <stdint.h>  // 包含标准库头文件，提供 uint_fast32_t 和 uint_least32_t 类型定义

#ifdef __cplusplus
extern "C" {  // C++ 兼容性声明，确保 C++ 编译器正确处理 C 函数名
#endif

#define SFT_DOWNWARD_Y 0x01  // 渲染标志位：指示 Y 轴向下为正方向

// 前向声明，用于定义指针类型
typedef struct SFT          SFT;
// 字体结构体，包含字体文件的所有信息
typedef struct SFT_Font     SFT_Font;
// 无符号 32 位字符类型，与 char32_t 兼容，用于表示 Unicode 字符
typedef uint_least32_t      SFT_UChar;
// 无符号快速 32 位整数类型，用于表示字形索引
typedef uint_fast32_t       SFT_Glyph;
// 行度量结构体，包含字体的行间距信息
typedef struct SFT_LMetrics SFT_LMetrics;
// 字形度量结构体，包含单个字形的度量信息
typedef struct SFT_GMetrics SFT_GMetrics;
// 字距调整结构体，包含两个字形之间的间距调整
typedef struct SFT_Kerning  SFT_Kerning;
// 图像结构体，包含渲染后的像素数据
typedef struct SFT_Image    SFT_Image;

// 字体渲染上下文结构体
struct SFT
{
	SFT_Font *font;      // 指向字体文件的指针
	double    xScale;    // X 轴缩放因子
	double    yScale;    // Y 轴缩放因子
	double    xOffset;   // X 轴偏移量
	double    yOffset;   // Y 轴偏移量
	int       flags;     // 渲染标志位，如 SFT_DOWNWARD_Y
};

// 行度量结构体
struct SFT_LMetrics
{
	double ascender;  // 基线到字体最高点的距离（正值）
	double descender; // 基线到字体最低点的距离（负值）
	double lineGap;   // 两行之间的间距
};

// 字形度量结构体
struct SFT_GMetrics
{
	double advanceWidth;    // 字形的前进宽度，即绘制完成后 X 轴的偏移量
	double leftSideBearing; // 字形原点到左边缘的距离
	int    yOffset;         // 字形在 Y 轴方向的偏移量
	int    minWidth;        // 渲染该字形所需的最小宽度
	int    minHeight;       // 渲染该字形所需的最小高度
};

// 字距调整结构体
struct SFT_Kerning
{
	double xShift;  // X 轴方向的字距调整量
	double yShift;  // Y 轴方向的字距调整量
};

// 图像结构体
struct SFT_Image
{
	void *pixels;  // 指向像素数据的指针
	int   width;   // 图像的宽度
	int   height;  // 图像的高度
};

// 获取 libschrift 库的版本信息
const char *sft_version(void);

// 从内存中加载字体文件
// 参数：mem - 指向字体数据的指针，size - 字体数据的大小
// 返回：加载成功返回字体指针，失败返回 NULL
SFT_Font *sft_loadmem (const void *mem, size_t size);

// 从文件中加载字体文件
// 参数：filename - 字体文件的路径
// 返回：加载成功返回字体指针，失败返回 NULL
SFT_Font *sft_loadfile(const char *filename);

// 释放字体指针占用的内存
// 参数：font - 要释放的字体指针
void      sft_freefont(SFT_Font *font);

// 获取字体的行度量信息
// 参数：sft - 渲染上下文，metrics - 存储度量信息的指针
// 返回：成功返回 0，失败返回非 0
int sft_lmetrics(const SFT *sft, SFT_LMetrics *metrics);

// 将 Unicode 字符映射为字形索引
// 参数：sft - 渲染上下文，codepoint - Unicode 字符编码，glyph - 存储字形索引的指针
// 返回：成功返回 0，失败返回非 0
int sft_lookup  (const SFT *sft, SFT_UChar codepoint, SFT_Glyph *glyph);

// 获取单个字形的度量信息
// 参数：sft - 渲染上下文，glyph - 字形索引，metrics - 存储度量信息的指针
// 返回：成功返回 0，失败返回非 0
int sft_gmetrics(const SFT *sft, SFT_Glyph glyph, SFT_GMetrics *metrics);

// 获取两个相邻字形之间的字距调整信息
// 参数：sft - 渲染上下文，leftGlyph - 左侧字形索引，rightGlyph - 右侧字形索引，kerning - 存储字距调整的指针
// 返回：成功返回 0，失败返回非 0
int sft_kerning (const SFT *sft, SFT_Glyph leftGlyph, SFT_Glyph rightGlyph,
                 SFT_Kerning *kerning);

// 渲染单个字形为图像
// 参数：sft - 渲染上下文，glyph - 字形索引，image - 存储图像数据的指针
// 返回：成功返回 0，失败返回非 0
int sft_render  (const SFT *sft, SFT_Glyph glyph, SFT_Image image);

#ifdef __cplusplus
}  // 结束 C++ 兼容性声明
#endif

#endif  // 头文件包含保护结束

